PraxisBibleNT 앱 전환 전략

vercel.json 최종 확정 (목사님 안이 정답입니다)

현재 가장 잘 작동하고 있는 아래 코드를 그대로 유지하세요.

{
  "cleanUrls": true,
  "trailingSlash": false,
  "rewrites": [
    { "source": "/manifest.json", "destination": "/static/manifest.json" },
    { "source": "/sw.js", "destination": "/static/sw.js" },
    { "source": "/icon-192.png", "destination": "/static/icon-192.png" },
    { "source": "/icon-512.png", "destination": "/static/icon-512.png" },
    { "source": "/apple-touch-icon.png", "destination": "/static/icon-192.png" },
    { "source": "/:path*", "destination": "/:path*" }
  ]
}

2. 완벽한 sw.js (static/sw.js)

단순한 등록을 넘어, 브라우저가 "이 사이트는 진짜 앱이다"라고 신뢰하게 만드는 필수 로직입니다.

JavaScript

// 서비스 워커 버전 관리
const CACHE_NAME = 'pxkor-bible-v1';

// 설치 시 즉시 활성화
self.addEventListener('install', (event) => {
  console.log('[Service Worker] Installing...');
  self.skipWaiting();
});

// 활성화 및 이전 캐시 정리
self.addEventListener('activate', (event) => {
  console.log('[Service Worker] Activating...');
  event.waitUntil(clients.claim());
});

// 설치 메뉴 활성화를 위한 필수 Fetch 이벤트
// 네트워크 우선 전략으로 항상 최신 정보를 보여줍니다.
self.addEventListener('fetch', (event) => {
  event.respondWith(
    fetch(event.request).catch(() => {
      // 오프라인일 때만 캐시에서 찾음
      return caches.match(event.request);
    })
  );
});

완벽한 manifest.json (static/manifest.json)

안드로이드 S25 Ultra와 아이폰 모두에서 최상의 아이콘 퀄리티를 보장하는 설정입니다.

{
  "short_name": "PraxisBibleNT",
  "name": "프락시스 신약성경 연구소",
  "description": "김기천 목사의 신약성경 연구소 앱입니다.",
  "icons": [
    {
      "src": "/icon-192.png",
      "type": "image/png",
      "sizes": "192x192",
      "purpose": "any maskable"
    },
    {
      "src": "/icon-512.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "any maskable"
    }
  ],
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#284b63",
  "background_color": "#ffffff",
  "scope": "/",
  "lang": "ko-KR"
}

• 포인트: purpose: "any maskable"은 최신 기기에서 아이콘이 잘리지 않게 해주는 핵심 옵션입니다.

        {/* PWA 설정 시작 */}

        <link rel="manifest" href="/manifest.json" />

        <meta name="theme-color" content={cfg.theme.colors.lightMode.secondary} />

        <link rel="apple-touch-icon" href="/icon-192.png" />

  

        <script dangerouslySetInnerHTML={{ __html: `

          if ('serviceWorker' in navigator) {

            window.addEventListener('load', () => {

              // 경로를 './sw.js'로 수정하여 현재 위치에서 찾도록 강제함

              navigator.serviceWorker.register('./sw.js', { scope: '/' })

                .then(reg => console.log('성공: 서비스 워커가 등록되었습니다!', reg))

                .catch(err => console.log('실패: 서비스 워커 등록 오류:', err));

            });

          }

        ` }} />

        {/* PWA 설정 끝 */}

PWA는 **Progressive Web App(프로그레시브 웹 앱)**의 약자로, 웹사이트를 마치 스마트폰의 일반 앱(네이티브 앱)처럼 사용할 수 있게 만드는 기술을 의미합니다.

주요 특징과 장점은 다음과 같습니다.

1. 주요 특징

• 설치 가능: 브라우저 주소창 옆이나 메뉴에서 '앱 설치' 버튼을 눌러 스마트폰 홈 화면이나 PC 바탕화면에 아이콘을 추가할 수 있습니다.

• 오프라인 작동: '서비스 워커(Service Worker)'라는 기술을 통해 인터넷 연결이 없거나 불안정한 상태에서도 사이트의 일부 기능을 사용할 수 있습니다.

• 푸시 알림: 일반 앱처럼 사용자에게 중요한 업데이트나 메시지를 푸시 알림으로 보낼 수 있습니다.

• 빠른 속도: 캐싱 기술을 사용하여 웹사이트보다 로딩 속도가 훨씬 빠르고 부드럽게 작동합니다.

2. 왜 사용하나요?

• 앱스토어 불필요: 구글 플레이스토어나 애플 앱스토어에 등록하고 심사받는 과정 없이, 웹 접속만으로 즉시 배포하고 설치를 유도할 수 있습니다.

• 개발 비용 절감: 안드로이드와 아이폰용 앱을 따로 만들 필요 없이 하나의 웹 코드로 모든 기기에서 앱처럼 작동하게 할 수 있습니다.

3. 이전 질문의 코드와 연결

사용자님이 보여주신 Head.tsx의 코드는 바로 이 PWA 기능을 활성화하기 위한 설정입니다.

• manifest.json: 앱의 이름, 아이콘, 테마 색상 등을 정의하는 명세서입니다.

• serviceWorker.register: 오프라인 작동과 빠른 로딩을 가능하게 하는 엔진(서비스 워커)을 브라우저에 등록하는 코드입니다

2. 개발자 도구(F12)를 통한 정밀 진단

목사님께서 이전에 사용하셨던 Sources 탭 옆의 Application 탭을 활용합니다.

1. 브라우저에서 F12를 누릅니다.

2. 상단 메뉴에서 Application 탭을 클릭합니다. (안 보이면 >> 모양을 누르세요)

3. 왼쪽 메뉴에서 다음 두 곳을 확인합니다.

   • Manifest: 만드신 이름(PraxisBibleNT), 아이콘, 배경색 등이 화면에 잘 나오는지 확인합니다. 만약 여기에 에러 메시지가 없다면 통과입니다.

   • Service Workers: sw.js 옆에 초록색 불과 함께 Activated and is running이라는 메시지가 떠 있어야 합니다.